8bitfiles.net/archives/archives.tar/archives/compuserve-file-archive/05 Programming/INTRO.TXT

Text File | 2019-04-13 | 25KB | 572 lines

Unix 128 v3.00 Notes              12 March 1991                           Page 1



Contents:    I.    Building the Unix 128 System...................1
             II.   Distribution and Rights........................1
             III.  Introduction to the Unix 128 System............2
             IV.   Introduction to ftp............................3
             V.    Introduction to the nroff Package..............5
             VI.   Introduction to the as Assembler...............7
             VII.  Introduction to the emacs Text Editor..........9
             VIII. Introduction to Telecommunications With tip....11

I.  Building the Unix 128 System.
     1.  System requirements:  a Commodore 128 computer, a 1571 disk drive, and
an 80-column RGB monitor.
     2.  Most people will fetch this system via anonymous ftp to the Milton ftp
site.  If this is the case, you must get the two .lnx files (unix128v3a.lnx and
unix128v3b.lnx), and download them in binary mode  (as  well as  the  lynx.c128
de-archiver, also found at Milton.)  Save these files on one double-sided disk,
and unarchive them.
     3. It is necessary to write all the other necessary system files  to  disk
by  typing  RUN "MAKE" from BASIC. This writes 8 SEQ files (.login [system init
file], author [about me], nroff.hlp [a help file  for  nroff,  accessable  from
emacs by  typing  ESC-x nroff], nroff.tbl [the printer table for nroff], passwd
[the system  password  file],  stdlib.i  [assembler  macros],   polish.ef   and
cyrillic.ef [polish and russian fonts for emacs- ESC-X FONT]) to the disk.
     The last system file that needs to be written is the disk  directory.   To
write this,  you  need  to  log  in (if it asks you for a username/password use
root/root.) and type % fsck.  This does  a  filesystem  consistency  check  and
writes the filesystem to the disk.
     That's all there is to it...



II.  Distribution and Rights.
     1. This set of programs is distributed without warranty  or  guarantee  of
any kind (in other words, if it transforms your 128 into a thermonuclear device
and vaporizes your neighborhood upon execution, it's not my fault.)
     2.  This program set may be freely redistributed as long  as  it's  intact
with  all documentation and code (excluding the sources, which no one needs). I
wish for my name to stay with the package,  and I  retain  all  copyrights  and
patents to all the source code that I wrote. Don't even think of copying any of
this stuff under your own name (or even worse-  selling  it...).  The  built-in
wrongdoing-detection circuits  will  take control of the nearest Electric Knife
and kill you.
     3.  Bug reports, gripes, $10 if you like this program may be sent to:
             Gregg Riedel
             20 Ellbert Street
             Smithtown, NY 11787
(it's my home address, but it's a little more stable than my college  address.)
I will probably graduate SUNY-Binghamton around Spring '93 - I should retain my
Consultant account until then:  [e-mail]




Unix 128 v3.00 Notes              12 March 1991                           Page 2


III.   Introduction to the Unix 128 System:

Unix 128 is not "real Unix" by definition.  A "real Unix" system:
     1. is multiprocessing- it can do more than one task "at  the  same  time."
This  feature could be emulated (partially) in software on the 128, but it would
be so slow and limited that it would cripple the system.
     2. has true pipelining-  input and output can be freely redirected.   Unix
128 does not have true pipelining.  However, you can freely redirect just about
any output to a file or the printer (by ending a  command  line  with  lpr  or
>filename).  I'll probably reserve true input redirection for a later release.
     3. has a true heirarchial filesystem-   Implementing  a  true  heirarchial
filesystem in  which  Unix  controlled  all  aspects of disk i/o would mean not
having compatibility with CBM DOS disks, which I wanted to retain.

Functions Compatible with "Real" Unix:

In addition to being a useful tool for development and  for  learning  to  move
through a  Unix  environment, Unix 128 has some features useful for interaction
with Unix mainframes:

1.  tip:  The tip modem package will interface through a modem to  most  remote
"real  Unix"   systems.   It  provides  (almost)  VT-100  compatibility,  VT-52
compatibility, and a raw mode for communication with other Commodore systems.

2.  tar:  tar is the tape archive that  "real  Unix"  systems  use  to  combine
multiple files  into  one  file to place on a backup tape.  Unix 128's tar will
both create and dissolve these tar files in  a  format  compatible  with  "real
Unix."  Note:   if you dissolve a tar created on "real Unix" that contains text
files, these files will be in ASCII format, not PETSCII format (tHE  cASES  aRE
rEVERSED).  You  can  invoke  'dd'  with  the -s option to fix this problem (in
English, type 'dd -s oldfile newfile')

3.  uuencode/uudecode:  This is a coder/decoder package that makes "real  Unix"
binaries into  text  files  for  mailing.   The  Unix 128 versions of these two
programs should be compatible with "real  Unix",  with  the  exception  of  the
ASCII/PETSCII problem mentioned above.

4.  nroff: nroff will accept documents formatted for nroff or troff without the
special macros  for  tables  and  equations  ("standard" nroff).  This is quite
helpful when you'd like to edit a paper  on  a  unix  mainframe,  but  continue
editing and print or preview the paper at home under Unix 128.








Unix 128 v3.00 Notes              12 March 1991                           Page 3



IV.  Introduction to ftp

ftp, the file transfer program, is a combination  of  a  unique  file  transfer
protocol and a  set  of terminal instructions designed to transmit and recieve
files and other data between two Unix 128 sites.  It is not compatible with the
Internet ftp used between BSD, DEC, SUN and other large-scale Unix systems.  It
is not used for remote login to any system- use 'tip' for logins.

The ftp command invokes one of two modes. The first mode (remote terminal mode)
is used  to  originate  a modem communications link to another Unix 128 system.
The second mode (server mode) is used to answer incoming calls  and  act  as  a
fileserver.

To invoke remote terminal mode, type % ftp or  % ftp phone-number.  If a  phone
number is given, ftp will automatically dial that number and attempt to connect
to another Unix 128 system (the system you dial must already be running in  ftp
server mode.)

To invoke server mode, type % ftp -s.  ftp will wait for  the  phone  to  ring,
answer it, and begin the session.

                       --- Remote Terminal Commands ---

The following commands are available at the ftp> prompt:

?              Get help (list the command summary)
ascii          Save incoming files as SEQ, don't convert PETSCII<->ASCII
binary         Save incoming files as PRG, don't convert PETSCII<->ASCII
bye            Hang up the phone, quit ftp and return to Unix 128
cd [dir]       Change directory to [dir]
close          Hang up the phone but do not exit ftp.
convert        Binary conversion of PRG files to SEQ files.
dir            Read current remote directory
get [file]     Get a file from the remote system.  Select ascii, text, or
               binary first to assure the proper file type and conversion.
hash           Show a hash mark (#) for every 512 bytes transferred.  This
               command toggles hash mark printing on and off.
open [number]  Dial a phone numbr and attempt to connect to a remote system.
send [file]    Send a file to the remote system.
text           Save incoming files as SEQ files, convert PETSCII<->ASCII
               (There is almost no need for this command.  When in doubt,
               use ascii and convert later with 'dd -s')


                           --- Server Commands ---

The server allows 1 input: CTRL-C to break if someone is  NOT  connected.   File
transfers and directory requests are automatic.  Important:  the server doesn't
know what type of file isn't incoming, so it saves everything as  un-translated
program (PRG)  files.  If you need to do a translation later, use the 'convert'
command from the ftp> prompt.







Unix 128 v3.00 Notes              12 March 1991                           Page 4



                           --- The ftp Protocol ---

ftp uses a special X-Modem derived protocol for  file  transfers.  First,  a
request goes from the remote terminal to the server telling it to either send
or receive a file. The file is sent in 128 byte blocks in the following
format:

                    [ 127 bytes of data ] [ control byte ]

The control byte is one of three values.  If it is 0, another block is  coming.
If it  is Control-Y or Control-Z, then this is the last block and the last byte
of valid data is the one that is not equal to the control  byte  (If  the  last
valid byte  is  not  Control-Z then the control byte will be Control-Z.  If the
last valid byte is Control-Z, Control-Y will be the control byte.)

All data connections are done with 8 data bits, no parity, 1 stop bit, at  1200
baud.






Unix 128 v3.00 Notes              12 March 1991                           Page 5



V.  Introduction to the nroff Package.

nroff is a text formatting package that is "mostly" compatible with plain nroff
and troff source files (no macros are included with
this release for table (tbl)
or equation (eqn) processing). nroff is not a "word processor" or "editor", but
a pass-thru text formatter. You must enter text on any editor or word processor
(emacs is fine) and then type % nroff -p file to print it or  % nroff  -v  file
to preview it.

nroff provides the powerful features associated with many  word  processors.  A
short list of features includes:

- n-line spacing (single space, double space ...)
- line justification
- centering
- right alignment
- multiple columns (1, 2, or 3 columns)
- printer-dependent function macros for underline, reverse, italics, bold,
     super- and subscript and custom graphics
- 3-part headers (left, center, and right aligned)
- full control of page offset, line length, and page length

                         --- Command Line Options ---

nroff may be invoked with several command-line options in the format:
% nroff (options) filename
The options are:
   -i  Interactive formatting setup first.
   -v  Video preview only
   -p  Print document only
   -S  Use my own symbol table instead of 'nroff.tbl.'  Example:  -Smytable
A command line might look like: % nroff -i -Smytable -p thisfile.
The nroff command takes a single document filename.

                         --- Formatting Commands ---

All formatting commands must begin with a period (.) that is at  the  far  left
(first column)  of the source document.   The following list can be viewed from
within emacs by typing ESC-X NROFF. The formatting commands are as follows:

 .bn N         Bold the next N input lines.*
 .bp (N)       Forced end-of-page (if N is given, it is the next page number.)
 .br           Break (exit this file).
 .ce N         Center the next N input lines.
 .cl N         Break text into N (=1,2,3) columns
 .cs N         Put N spaces between columns, if appropriate
 .de \xx yy    Define macro \xx as the string yy.
 .dr           Use draft mode.*
 .ec C         Set the escape character to C (default=\).
 .eo           Ignore escape codes.
 .ex           Exit this file.
 .fc           Tell nroff to begin a new page to force changes made to be
                    interpreted (column changes, header changes etc...)
 .ft fontname  Use font 'fontname'.  This is understood but ignored.
 .il N         Italicize the next N input lines.*
 .in N         Indent paragraphs N spaces (default=5).







Unix 128 v3.00 Notes              12 March 1991                           Page 6



 .ll N         Set line length to N characters.
 .lm N         Set left margin to N characters (default=0).
 .ls N         Set line spacing to N (1=single space, 2=double space etc.)
 .lt N         Title is N characters long.
 .ne N         Need N vertical spaces (i.e. skip N lines).
 .ni           No indent
 .nq           Use near-letter-quality mode.*
 .nx filename  Load next file 'filename'.
 .pl N         Set page length to N (paper is usually 66 lines, default=60).
 .pn N         Next page is number N.
 .po N         Set page offset to N (same as left margin).
 .ps N         Pitch size in c.p.i. (Usually 10 or 12).*
 .ra N         Right-align the next N input lines.
 .rm N         Set right margin to N characters (default=79).
 .rv N         Reverse (white-on-black) the next N input lines.*
 .ta N         A tab is the tab character repeated N times (default=8).
 .tc C         Tab character is C (default=" ").
 .tl 'l'c'r'   Three part title (l=left, c=center, r=right).
 .ul N         Underline the next N input lines.*

*  Requires a printer-dependent setting in 'nroff.tbl'

                      --- Default Macros (nroff.tbl) ---

\bs     backslash                      \su     superscript on
\ca     carat                          \sb     subscript on
\cb     close curly brace              \s0     super/subscript off
\ob     open curly brace               \dg     degree symbol
\pi     pipe symbol (vertical bar)     \in     integral symbol
\tl     tilde                          \sg     capital sigma
\dt     capital delta                  \sq     square root symbol
\g [7 integers (0-255)]\  custom graphics







Unix 128 v3.00 Notes              12 March 1991                           Page 7



VI.  Introduction to the as Assembler Development Package

as is the Unix 128 8510 assembler. It takes a single source file, processes the
Unix 128  extensions, writes an object file (*.o) that contains only valid 8510
assembler opcodes / operands, then converts the object  files  and  writes  the
binary machine language file 'a.out.'

The first two bytes of 'a.out' contain the start address of the code (where  it
is loaded)  and  the  rest of the file contains the single-byte opcodes and the
bytes of data needed.

The extensions to standard assembler are as follows:
1.  The first line of any assembler  source  code  must  be  the  word  'start'
followed by either a decimal number or a '$' and a hexidecimal number.  This is
the start address of the code which is  written  directly  to  'a.out.'   If  a
'start' line is not found, an error will occur.

2. One or more lines may be given that begin with  the  word  'include'  and  a
source filename  that contains valid macro definitions (see 4).  The purpose of
this statement is similar to the C #include <library.h>: to include  macros  of
standard code.   An  include file, 'stdlib.i', is given with this package as an
example.  Example:  include stdlib.i

3.  A data section may be given, so that you may label common constants. A data
section consists  of  the  word 'data' on its own line, followed by one or more
data lines, and followed by the word 'endd' (end-data) on its own line.  A data
line consists  of  a  data  label,  the  word  'equ',  and a decimal value or a
hexidecimal value preceeded by a '$'
Example:
   data
     zero equ $00
     two equ 2
   endd
Wherever the names 'zero' or 'two' are encountered, they are replaced with  the
appropriate data value.

4.  Macros are units of code that are given a name.  They are defined once, and
expanded wherever  the macro name is found.  A macro definition begins with the
word 'macro', a single space, and the macro name.  One or more lines  of  valid
8510 source code are given on separate lines, and the word 'endm' (end-macro)
is given to conclude the macro definition.
Example:
   macro foo           (start a macro named foo)
     lda #$00
   endm                (end of this macro)
Whenever the name 'foo' is encountered in the source code, it is replaced  with
the line  'lda  #$00'.  Macros cannot be given parameters.  Standard macros are
usually used for system calls such as setting fast mode or clearing the screen.

5.  Comments can be given on separate lines  by  beginning  that  line  with  a
semicolon (;).  Example:
   ;This is a comment







Unix 128 v3.00 Notes              12 March 1991                           Page 8



6.   Any line may be given a name by which it can be referred. This removes the
tedium of keeping track of addresses for jumps and branches. The name  must  be
followed immediately by a colon (:).  Example:
 line:  ldx #zero
        sta $0400,x
        jmp line

**WARNING**  Be very careful not to use valid operand names  for  line  labels,
data labels or macro names.  The preparser will replace all occurences of label
names with the appropriate data. (For example, if you label a line  with  jsr:,
every time  you  used jsr in your program it will be replaced by the address of
the line to which the line label refers!)

                         --- Command Line Options ---

as can be invoked with several different options from the Unix 128 command line:

   % as -h           :Prints a help screen.
   % as -d beg end   :Disassembles memory from beg to end
   % as -v beg end   :Views memory from beg to end
   % as filename     :Parses 'filename' --> 'filename.o' --compiles--> 'a.out'

                    --- Valid 8510 Mnemonics (op-codes) ---

adc     and     asl     bcc     bcs     beq     bit     bmi     bne     bpl
brk     bvc     bvs     clc     cld     cli     clv     cmp     cpx     cpy
dec     dex     dey     eor     inc     inx     iny     jmp     jsr     lda
ldx     ldy     lsr     nop     ora     pha     php     pla     plp     rol
ror     rti     rts     sbc     sec     sed     sei     sta     stx     sty
tax     tay     tsx     txa     txs     tya

                            --- Valid Keywords ---

start   macro   endm    data    endd    include equ


General Notes:
1.  Use all lower case for keywords and op-codes, and use a single space
       between op-codes and operands.
2.  There is a limit of 1500 lines of source code (255 characters per line)
3.  There is a limit of 75 macros of 50 lines (255 char/line) each.
4.  There is a limit of 100 unique line labels.
5.  There is a limit of 100 data items in the data section.







Unix 128 v3.00 Notes              12 March 1991                           Page 9



VII.  Introduction to the emacs Text Editor.
Emacs is a powerful text editor for use under Unix 128. It is  not  a  document
formatter or  'word  processor'-  the  most advanced text previewing feature is
word-wrap. Text should  be  passed  to  nroff  for  formatting  (line  spacing,
columns, justification etc.)

Emacs allows up to 700 lines of text (of 80 characters / line).  It  loads  and
saves SEQ type files that are compatible with most other word processors. Emacs
also features DiskEd, to enter CBM-DOS commands. It has help screens for itself
as well as a command reference for writing nroff source files.  It has multiple
text editing features like setting and copying regions, 'killing' and 'yanking'
lines of  text,  commands to move to the start and end of lines, up and down by
screens, and commands to move to the start and  end  of  text.   Files  can  be
inserted into  the  text.   There is font support, and 2 partial fonts (one for
special Polish characters and one for  the  Russian  (cyrillic)  alphabet)  are
included.

                               --- Regions ---

A region is defined as all the text in between the 'mark' and the current
cursor position.  A  mark  is  set  by  typing  (Commodore) (SPACE).  Once a
region is defined, you can:
  CONTROL-c : copy region as kill. This allows you to copy the region into  the
kill buffer to be copied back into the text with CONTROL-y (yank).
  Rot-13 region : Perform the rot-13 transformation on the region  (which  maps
each letter 13 positions away; a-->m, b-->n, m-->a etc)

                      --- Expanded Command Reference ---

(C-key - Control+key    E-key - Hit ESC then key)
C-a      Move the cursor to the beginning of the current line.
C-b      Move the cursor back one character (same as 'cursor left')
C-c      Copy the currently marked region into memory, to be retrieved with
         C-y (yank line)
C-d      Enter DiskEd, which allows CBM DOS commands to be executed.
C-e      Move the cursor to the end of the current line.
C-f      Move the cursor forward one character (='cursor right')
C-g      Quit prompt (general abort for commands)
C-h      Get Help!!!
C-k      Delete line from cursor to end of line, copying the line to memory.
C-l      Redraw the screen.
C-n      Move the cursor to the next line (='cursor down')
C-p      Move the cursor to the previous line (='cursor up')
C-r      Rot-13 a previously marked region
C-v      Move down by a full screen
C-w      Write this file as...
C-y      Yank a line from memory to the current cursor position.
C-x c    Clear text memory.
C-x e    Copy the keyboard macro defined with C-( and C-)
C-x f    Find phrase (maybe).
C-x i    Insert a file at the current cursor position.
C-x p    Print the contents of memory.
C-x s    Save file with current filename.
C-x v    View document with word-wrap.
C-x C-c  Quit to Unix 128.
C-x C-f  Load a file into memory, erasing current memory contents.







Unix 128 v3.00 Notes              12 March 1991                          Page 10



C-x (    Write keyboard macro
C-x )    End keyboard macro
C-x =    Cursor information (what line, character etc)
C-x +    Insert a line at the cursor.
E-<      Move the cursor to the beginning of the file.
E->      Move the cursor to the end of the file.
E-v      Move up by 1 full screen.
E-x ?    Show bound commands (nroff help, fonts etc.)

Of course, the abbreviated command reference may be viewed at any time by typing

C-h, without disturbing your document.






Unix 128 v3.00 Notes              12 March 1991                          Page 11



VIII.  The tip Telecommunications Program.

     Tip is used to connect to mainframes or other Unix 128 systems  using  the
telephone lines.   It  can use a wide variety of protocol and terminal settings
and will be compatible with most systems.
     All of the features of tip can be accessed through the  menu  screen.   To
bring up  the  menu, press the ALT key on the upper left of the keyboard.  This
brings up the following menu items (use the cursor keys/[RETURN] to select):

Baud Rate:         the speed of communication (300 and 1200 are most common)
Data Bits:         7 or 8 data bits are supported
Parity:            even, odd, space, mark or no parity are supported
Stop Bits:         1 or 2 stop bits are allowed
Duplex:            full(no local echo) or half(local echo) duplex
Terminal Type:
    -VT100:        use VT100 emulation.  This is not perfect emulation, but
                     will provide most of the VT100 command set.  If you're
                     looking for 100% VT100/102 compatibility, get DesTerm 2.00
    -VT52:         use VT52 emulation.
    -Commodore:    also called 'raw' mode, this doesn't interpret any of the
                     control codes encountered.  This is useful when talking
                     to other Commodore systems.
Dial:              Enter a phone number and tip will dial it and attempt to
                     connect to the host computer.  One of the following codes
                     will be returned:
                        CONNECT       = connected at 300 baud
                        CONNECT 1200  = connected at 1200 baud
                        BUSY          = the host is busy
                        VOICE         = a human being answered the phone.
Hang Up:           Hang up the phone.
Clear Display:     This just clears the screen.
Buffer:
    -Capture On:   This will copy everything that comes across the screen
                     (except menus etc.) to memory
    -Capture Off:  This turns off the copy-to-memory feature.
    -Clear Buffer: Erase all buffer memory.
    -Save Buffer:  Save the contents of the buffer in a disk file.
    -Print Buffer: Print the contents of the buffer on the printer.
    -View Buffer:  Type the contents of the buffer on the screen (use the
                     NO SCROLL key to pause / resume.)
ASCII Upload:      Enter a filename and tip will just type the file to the
                     modem.  To receive the file on a mainframe, you must first
                     type:
                       VAX/VMS: $ create filename (when done, type CTRL-Z)
                       Unix: % cat > filename   (when done, type CTRL-D)
Quit to Unix:      Returns to the Unix 128 shell prompt (%).  You can leave tip
                     without hanging up, do other work, and return to tip
                     safely.  Remember to hang up the phone when you're
                      finished.
(Terminal Mode):   Return to terminal mode.